This change is part of the allocator_api feature set #32838 (also see wg-allocators roadmap or libs-team ACP).
The previous attempts at adding an allocator parameter to string are at rust-lang/rust#101551, and rust-lang/rust#79500 (I think those authors should get much of the credit here, I am re-writing what they worked out in those threads).

workaround

There is a type inference ambiguity introduced when adding a generic parameter to a type which previously had none, even when that parameter has a default value (more details in rust-lang/rust#98931). I've done the same workaround as rust-lang/rust#101551, which is to make alloc::string::String a type alias to String<Global>, but I've arranged the modules a bit differently to make rebase/merges a bit easier.

This workaround unfortunately changes the type name of the String language item, and that would be user-facing in error or diagnostic output. I understand from this comment that this change is acceptable.

changes to existing API

Most of the methods on the original String have been implemented for the generic version instead. I don't foresee anything more moving from String<Global> to String<A>, as the remaining methods are all constructors which implicitly use the Global allocator.

There are three general types of changes:

1. methods which don't allocate: here we just change impl Foo for String to impl<A: Allocator> Foo for String<A>
2. converting to/from other allocator generic types like Vec<u8, A> and Box<str, A>: here we can use the existing allocator from those types.
3. methods which clone from some other type with an allocator: here it's ambiguous whether the end result should be String<A>, String<Global>, or String<impl Allocator + Default>, etc; in general I try to leave these out of this change, but where some analogous change was made to Vec<T, A> I follow that.

new methods

Some methods have been added to String<A> which are not strictly necessary to land this change, but are considered helpful enough to users, and close enough to existing precedent in Vec<T, A>. Specifically, 4 new constructors (new_in, with_capacity_in, try_with_capacity_in, from_raw_parts_in), 1 destructor (into_raw_parts_with_alloc), and 1 getter (allocator). Technically, the updated from_utf8_unchecked should be sufficient for constructing, but we can add some safe constructors so users don't have to sully themselves.

not implemented

Variants of from_utf{8,16}* which internally allocate or use Cow have been punted on this PR, maybe a followup would make sense to either rewrite them, or add some *_in variant.